home *** CD-ROM | disk | FTP | other *** search
/ CU Amiga Super CD-ROM 17 / CU Amiga Magazine's Super CD-ROM 17 (1997)(EMAP Images)(GB)[!][issue 1997-12].iso / CUCD / Programming / DiceSource / doc / BEGINNER_README.DOC < prev    next >
Text File  |  1994-02-13  |  10KB  |  273 lines
  1.  
  2. beginner/help                        beginner/help
  3. beginner/beginner                    beginner/beginner
  4. beginner/beginner_readme                beginner/beginner_readme
  5.  
  6.                BEGINNER'S DOCUMENT FOR DICE
  7.  
  8.     (I)     The C Language
  9.  
  10.     (II)    Your first program, from start to end
  11.  
  12.  
  13.                      (I)
  14.                    THE C LANGUAGE
  15.  
  16.     It is not possible to describe the entirety of the C language in a
  17.     simple document file.  If you have no experience with the C language
  18.     and are trying to learn it the best thing to do is go to your local
  19.     bookstore (that has a computer section hopefully) and buy TWO different
  20.     ANSI C language books.  Really, TWO.  Look for a tutorial style book
  21.     and for a reference style book.  The tutorial style book will have many
  22.     self contained source examples that you can simply type in and run...
  23.     and figure things out by hacking on the examples and seeing the
  24.     results. The reference style book will have a comprehensive description
  25.     of all the standard calls available.  BE SURE YOU GET BOOKS THAT
  26.     DESCRIBE ANSI C rather than the original K&R C.  DICE is nearly 100% an
  27.     ANSI C compiler including nearly all the standard ANSI C functions.
  28.  
  29.     DME, the editor that comes with DICE, has a quick-reference capability
  30.     that allows you to place the cursor over a function name, hit a key, and
  31.     have the manual page for that function brought up in a separate window.
  32.     As you get familiar with DME please try out this function.    The key
  33.     sequence is control-right_bracket from DME.  If you have your own editor
  34.     that is able to generate standard ascii files you may use that in lieu of
  35.     DME.  However, note that DME was designed with programming in mind and
  36.     *does* have that quick-reference capability, and so once learned will
  37.     probably be more efficient for your purposes.
  38.  
  39.     As I have said, I cannot really *teach* you C in these flimsy manual
  40.     pages.  I can, however, give you some of the formatting methodolgy
  41.     to make your programs more readable to yourself and to others.
  42.     Unfortunately, bad habits tend to stick, so learning the right way
  43.     to do things from day 1 will go a long way.  The file METHODOLOGY.DOC
  44.     contains this information and assumes you already know C basics.
  45.  
  46.                      (II)
  47.              FIRST PROGRAM FROM START TO END
  48.  
  49.     After installing DICE boot your system.  If you run from the workbench
  50.     you must open a CLI or Shell window to fool around with DICE.
  51.  
  52.     NOTE:   From workbench the path might not be properly set up.  If
  53.     you:
  54.  
  55.     1> DCC
  56.  
  57.     and it comes back command not found, and DCC *does* exist on the floppy
  58.     or in-memory, then the path may not be properly set up.
  59.  
  60.  
  61.     (1) Creating the source code.  CD into some scratch directory... I use
  62.     T: here.
  63.  
  64.     1> CD T:
  65.  
  66.     (2) Edit a new file.  You do not have to RUN the editor, but it is always
  67.     nice because you can run the compiler without exiting the editor. This
  68.     tutorial expects you to RUN the editor:
  69.  
  70.     1> RUN DME test.c
  71.  
  72.     (3) DME brings up an editor window on the workbench.  Pressing the
  73.     right mouse button should bring up a menu (assuming you are not
  74.     already familiar with DME and installed it from the DICE disks).
  75.     IF DME DOES NOT HAVE A MENU then the right mouse button will
  76.     probably iconify the window instead.  This means you forgot to
  77.     copy DCC:S/.EDRC into S: ... again, this file already exists if
  78.     you simply booted with a copy of the distribution disk so you should
  79.     see a menu.
  80.  
  81.     Um, that was just to make sure DME is configured right... you can let
  82.     go of the RMB (right mouse button) now.  If you flip through the
  83.     menu items available you will note that many options have keyboard
  84.     equivalents.  For further information on mapping keys to your own
  85.     macros read the DCC2:MAN/DME.DOC document.  You can read the
  86.     document by putting the DCC2: floppy into DF0: and selecting the
  87.     Project/Open-NewWin menu option (this brings up a new window so
  88.     you now have two, though the first one is covered.  To use the
  89.     same window use the Project/Open-Replace menu option).
  90.  
  91.     (4) Type in your program.  The cursor keys may be used to move
  92.     around.  control-cursor_key skips multiple lines while
  93.     shift-cursor_key skips to the top or bottom of the file.
  94.     Typing RETURN on the last line adds a new line to the file.
  95.     Typing RETURN in general inserts a new line after the current
  96.     line.
  97.  
  98.          BASIC DME KEY COMMANDS, REFER TO DCC2:MAN/DME.DOC FOR MORE
  99.          INFORMATION.  These comprise only a few of the many commands
  100.          available.  You can construct your own key macros and menu
  101.          options to your whim as you get better.
  102.  
  103.     <cursor-key>        move the cursor around.
  104.  
  105.     ctl-<cursor-key>    skip around
  106.  
  107.     shift-<cursor-key>  move to top of text, bottom of text, first column,
  108.                 or end-of-line
  109.  
  110.     <del>            delete a character.  Experiment with <del> and
  111.                 <backspace> to determine the differences between
  112.                 the two.
  113.  
  114.     shift-<del>        delete a LINE
  115.  
  116.     ctl-i            control-i, go into insert mode
  117.     ctl-o            control-o, go into overwrite mode
  118.  
  119.     alt-i            ICONIFY WINDOW.  Window becomes iconified (very,
  120.                 very small)... unclutters the workbench screen.
  121.                 You may uniconify by selecting the iconified
  122.                 window and hitting the right mouse button.
  123.  
  124.     help            brings up a new window (as in <f3>) with
  125.                 DCC2:MAN/DME.DOC in it.
  126.  
  127.  
  128.                 FILE LOAD, SAVE
  129.         All of these have equivalent Menu options
  130.  
  131.     <f1>            Insert a file.  The current filename and file
  132.                 in the window stays, but some other file is
  133.                 inserted into the current text... experiment
  134.                 with this with a few small text files.
  135.  
  136.     <f2>            Edit a new file... replaces the current window
  137.                 with a new file.  The old file is gone (not
  138.                 deleted, just not being edited any more).  If
  139.                 you made modifications to the current file a
  140.                 requester will pop up asking you if you want
  141.                 to really throw it away.
  142.  
  143.     <f3>            Edit a new file... opens up a new window for the
  144.                 new file after you type in the file name, the
  145.                 previous file window is still there though
  146.                 probably obscured... you can move and resize
  147.                 the windows however you wish.
  148.  
  149.     <f9>            save file
  150.  
  151.     <f10>            save file and close window (exits DME if this is
  152.                 the last window)
  153.  
  154.     c-q            Quit - same as the close window gadget.
  155.  
  156.  
  157.     (4A)    PROGRAM?  What Program?  This program:
  158.  
  159.     -------- top of file (this line not part of file) --------
  160.  
  161.     #include <stdio.h>
  162.     #include <stdlib.h>
  163.  
  164.     main()
  165.     {
  166.         puts("Hello World!");
  167.         return(0);
  168.     }
  169.  
  170.     -------- bottom of file (this line not part of file) -----
  171.  
  172.     (5) COMPILING THE PROGRAM
  173.  
  174.     Write out the file with F9
  175.  
  176.     You can either quit out of the editor or simply bring your CLI
  177.     window forward to compile the program.    Better, iconify the editor
  178.     window to unclutter your workbench screen!  To compile the program,
  179.     enter this line:
  180.  
  181.     1> dcc test.c -o test
  182.  
  183.     This tells DICE to compile and link test.c into an executable.    DICE
  184.     should grind on the file and then return another CLI prompt.  If any
  185.     requester comes up you are missing an assignment or two:
  186.  
  187.     DINCLUDE:    you are missing the DINCLUDE: assignment which
  188.             should be set to DCC:INCLUDE.
  189.  
  190.     DLIB:        you are missing the DLIB: assignment which should
  191.             be set to DCC:DLIB.
  192.  
  193.     "Unable to open dlib:Amigas13.lib or dlib:dlib:amigas13.lib"
  194.  
  195.         Means that you do not have amigas.lib installed in DLIB: ...
  196.         Amigas13.LIB is Amiga.LIB after being put through the LIBTOS
  197.         program and comes with the registered version of DICE.
  198.  
  199.         Double check that you have 'SETENV DCCOPTS -1.3' and that DLIB:
  200.         is assigned and amigas13.lib is in it, as well as other DICE
  201.         libraries.
  202.  
  203.     (6) RUN THE PROGRAM
  204.  
  205.     1> test
  206.     Hello World!
  207.     1>
  208.  
  209.     You can make the program residentable by compiling with the -r
  210.     option. A -r compiled program's executable will have the PURE bit
  211.     set automatically and may optionally be made resident.    Programs
  212.     not compiled with the -r option will not have the Pure bit set and
  213.     may not be made resident.
  214.  
  215.     1> dcc test.c -o test -r
  216.     1> test
  217.     Hello World!
  218.     1> resident test
  219.     1> test
  220.     Hello World!                <- much faster response!
  221.  
  222.     (7) ***** WARNING ***** ABOUT RESIDENTED EXECUTABLES
  223.  
  224.     It is a COMMON mistake when a programmer is making modifications
  225.     and recompiling a program to forget to REMOVE the program from
  226.     the resident list if it was placed on it.  I.E.
  227.  
  228.     1> resident test REMOVE
  229.  
  230.     The reason is simple... you make a change and recompile your
  231.     program.  But, you have already been the program resident. If you
  232.     run the program the 'old' version will be run.  Thus, you want to
  233.     either remove it from the resident list or re-resident the
  234.     executable.
  235.  
  236.     You can also force a program to be loaded from disk by providing a
  237.     full path to it.  I.E.
  238.  
  239.     1> resident test
  240.     1> test
  241.     Hello World!        <- uses resident version
  242.  
  243.     1> DF0:test        (or wherever you compiled test to)
  244.     Hello World!        <- uses disk version
  245.  
  246.  
  247.     (8)     PROGRAM EXAMPLES
  248.  
  249.     The registered DICE distribution comes with a large number of program
  250.     examples that should prove invaluable to a beginner.  Additionally,
  251.     every manual page includes a self-contained program example for
  252.     the particular function the page describes and this also should
  253.     prove invaluable when confusion arises.
  254.  
  255.     Please refer to the README for an overview, and also browse the
  256.     DICE disks from a CLI.    Unfortunately, due to space packing I
  257.     sometimes move things around and forget to update the
  258.     documentation.    The DME example is the best of the lot and is
  259.     on DCC3:, readme the README file on DCC3 for unpacking instructions.
  260.  
  261.     To run a DMakefile type the DMAKE command on the directory
  262.     containing the DMakefile.  I'm afraid the DMake is a huge
  263.     hack and not much good documentation is available for it, but
  264.     what documentation there is is in DCC3:MAN/DMAKE.DOC
  265.  
  266.     (9)
  267.     That terminates the tutorial.  Refer to the DCC:DOC and DCC2:MAN
  268.     directories for documents describing other executables (use DME
  269.     to bring these files up and browse through them).  Note that the
  270.     top few lines of each file contain a keyword that gives DME it's
  271.     quick-reference capability to the file.
  272.  
  273.